Creating Bitmaps With Disk-Based Pixel Images (IM: XG)

Inside Macintosh: QuickDraw GX Graphics /: Chapter 5 - Bitmap Shapes / Using Bitmap Shapes

Creating Bitmaps With Disk-Based Pixel Images
QuickDraw GX allows you to store the pixel image of a bitmap shapes in a disk file. To create this type of bitmap, you specify a predefined constant for the image field of the bitmap's geometry:
aBitmapGeometry.image = gxBitmapFileAliasImageValue;
The other fields of the geometry you can initialize as you would for other bitmaps:
aBitmapGeometry.width = widthOfDiskBasedImage;
aBitmapGeometry.height = heightOfDiskBasedImage;
aBitmapGeometry.rowBytes = rowBytesOfDiskBasedImage;
aBitmapGeometry.pixelSize = pixelSizeOfDiskBasedImage;

aBitmapGeometry.space = colorSpaceOfDiskBasedImage;
aBitmapGeometry.set = colorSetOfDiskBasedImage;
aBitmapGeometry.profile = colorProfileOfDiskBasedImage;
You still create the bitmap using the GXNewBitmap function:
aBitmapShape = GXNewBitmap(&aBitmapGeometry, &initialLocation);
You specify the file that contains the pixel image using the bitmap data source alias structure, which is defined by the gxBitmapDataSourceAlias data type:
struct gxBitmapDataSourceAlias {
   unsigned long fileOffset; /* offset (in bytes) to image */
   unsigned long aliasRecordSize; /* size of alias record */
   unsigned char aliasRecord[gxAnyNumber]; /* alias record */
};
To use this data type, you need to declare a variable to hold the structure:
gxBtimapDataSourceAlias anAlias;
Then, you need to set the three fields of the structure:

the aliasRecord field should contain a Macintosh Alias Manager alias record specifying the file containing the pixel image
the aliasRecordSize field should specify the size in bytes of the alias record
the fileOffset field should specify the offset in bytes from the beginning of the data fork of the file to the first pixel value of the pixel image

Once you've created the bitmap data source alias structure, you create a tag object to encapsulate the structure, using the call
anAliasTag = GXNewTag(gxBitmapFileAliasTagType, sizeOf(anAlias)
                      &anAlias);
Then you associate the tag object with the bitmap shape using the call
GXSetShapeTags(aBitmapShape, gxBitmapFileAliasTagType, 
               1,  /* first tag */
               -1, /* replace all tags of same type */
               1,  /* insert one new tag */
               &anAliasTag); /* tag to insert */
Now the disk-based bitmap is completely initialized. You can use most bitmap-related functions with this bitmap, but there are bitmap-related functions you cannot use. In particular, you cannot call the GXSetBitmapParts, GXSetShapePixel, GXNewViewDevice, or GXSetViewDeviceBitmap functions, as these functions would require QuickDraw GX to write to the file.
For more information about alias records, see the chapter "Alias Manager" of Inside Macintosh: Files.
For more information about tags and the GXNewTag function, see the chapter "Tag Objects" of Inside Macintosh: QuickDraw GX Objects. For information about the GXSetShapeTags function, see the chapter "Shape Objects" in that book.